Add text selection system with frame-level cell composition - #980

Problem

Background: why full-screen TUIs need virtual scrolling

Long-running interactive applications — coding assistants, chat clients, log viewers — accumulate content that far exceeds the terminal height. A single Qwen Code session can produce thousands of lines of conversation, tool output, and code blocks. Rendering all of this into the terminal's scrollback buffer creates two problems:

• Performance. Every re-render (on each keystroke, streaming token, or state change) requires Ink to erase and repaint the entire output region. With hundreds of lines in the scrollback, this causes visible flicker and high CPU usage. The terminal must process thousands of ANSI erase/write sequences per frame.
• Layout control. The application cannot anchor UI elements (input prompt, status bar, sticky panels) to fixed screen positions when the output region grows unboundedly into the scrollback.

Virtual scrolling solves both: the application enters alternate-screen mode (?1049h) to get a fixed-size viewport, then only renders the visible slice of content. As the user scrolls, the viewport window moves over the full dataset and the render output is recycled — much like a virtualized list in a GUI framework. The terminal sees a constant-height frame, eliminating flicker and enabling precise layout.

The selection problem

Alternate-screen mode and virtual scrolling together break text selection, which is a basic user expectation:

1. The scrollback buffer is empty. The alternate screen (?1049h) is a separate, fixed-size buffer with no scrollback history. Terminal emulators' native selection (click-drag, double-click word select, etc.) operates on the scrollback buffer. In alternate-screen mode there is nothing to select from — the content exists only as the current frame, which the terminal treats as ephemeral (by design — think vim, htop, less).

2. Virtual scrolling means the full content is never on screen. Even if a terminal emulator supports selection within the alternate screen, it can only select what's currently rendered in the viewport. Content that has been scrolled off is not in any terminal buffer — it exists only in the application's data model. Selecting across a range that spans multiple viewport-fuls of content is impossible through terminal-native mechanisms.

3. Ink's render pipeline is opaque to the application. Ink composites the yoga layout tree into a string of ANSI sequences and writes it to stdout. The application has no structured access to what's actually on screen — which characters are at which cell coordinates, which are selectable, how lines wrap and flow. Without this information, the application cannot implement its own selection that maps mouse coordinates to logical text content.

The result: users of full-screen Ink TUIs cannot select and copy text — code blocks, error messages, conversation content. For a coding assistant where copying generated code is a core workflow, this is a critical usability gap.

Solution

This PR adds a frame-level cell composition system that gives applications structured, per-cell access to the rendered frame, enabling mouse-driven text selection within Ink's rendering pipeline.

The key insight: Ink already walks the yoga tree and writes styled characters into an Output grid during rendering. This PR extends that grid with per-cell metadata (selectability, reading-flow grouping, line-break semantics) and exposes it through a FrameController bridge:

Application                          Ink Renderer
    |                                     |
    |-- setSelection({sx,sy,ex,ey}) ---->|  (schedules repaint)
    |                                     |
    |<---- publishFrame(cells[][]) -------|  (after each render)
    |                                     |
    |-- getFrame() / subscribe() -------->|  (read latest frame)

The application handles mouse events and selection logic; Ink provides the composited frame data and applies the selection highlight during serialization. Selection is a pure render-time concern — it never mutates committed frame state.

Public API

getFrameController(stdout): FrameController | undefined

Access the frame controller for a render instance (via the existing instances map).

FrameController

FrameCell

Each cell in the composited grid carries:

• type, value, fullWidth, styles — existing styled character data
• selectable: boolean — whether this cell participates in selection
• flowId: number | null — logical reading flow grouping

New <Text> props

Internal changes

• Output.get(selection?) — returns {output, height, cells, boundaries}. Cells carry selectable/flowId metadata. When a selection is provided, selected cells get a highlight background applied before serialization.
• renderNodeToOutput — threads flowIds/nextFlowId maps through the tree. Uses wrapTextWithMetadata instead of plain wrapText to track soft/hard line boundaries and per-row selectability.
• wrapTextWithMetadata — wraps text and returns {text, boundaries: TextBoundary[], selectableRows: boolean[]} for semantic copy reconstruction.
• renderer — accepts an optional selection parameter, creates flow tracking state, returns cells/boundaries alongside the string output.
• Ink class — creates a FrameController in the constructor, publishes frames after each render, reads selection state for highlight.

Testing

All 86 existing component tests pass. The feature is additive — no existing behavior changes when selection is not used.

This feature has been running in production in Qwen Code's TUI (via a patch on ink 7.0.3) for several months, supporting text selection in a full-screen alternate-screen TUI with virtual scrolling.